package module.StoreService;

import common.model.Entity.StoreEntity.Product;
import network.protocol.Response;
import java.util.List;
import java.util.Optional;

/**
 * {@code ProductService} 定义了商品（Product）相关的业务操作接口。
 * <p>
 * 主要提供以下功能：
 * <ul>
 *     <li>根据 ID 或名称获取商品</li>
 *     <li>获取所有商品，或按分类 ID / 分类名获取商品</li>
 *     <li>创建、更新、逻辑删除商品</li>
 *     <li>统计商品数量</li>
 *     <li>校验商品是否存在、名称是否存在</li>
 *     <li>更新商品库存与状态（如上架/下架）</li>
 * </ul>
 * <p>
 * 所有方法均返回统一封装的 {@link Response} 对象，
 * 调用方可根据该对象判断操作成功与否并获取相关数据。
 */
public interface ProductService {

    /**
     * 根据商品 ID 获取商品。
     *
     * @param id 商品的唯一标识
     * @return 包含商品对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<Product>> getProductById(long id);

    /**
     * 根据商品名称获取商品。
     *
     * @param name 商品名称
     * @return 包含商品对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<Product>> getProductByName(String name);

    /**
     * 获取系统中所有商品。
     *
     * @return 包含商品列表的响应对象；
     *         如果没有商品，则返回空列表
     */
    Response<List<Product>> getAllProducts();

    /**
     * 根据分类 ID 获取商品。
     *
     * @param categoryId 分类的唯一标识
     * @return 包含商品列表的响应对象；
     *         如果没有商品，则返回空列表
     */
    Response<List<Product>> getProductsByCategoryId(long categoryId);

    /**
     * 根据分类名称获取商品。
     *
     * @param categoryName 分类名称
     * @return 包含商品列表的响应对象；
     *         如果没有商品，则返回空列表
     */
    Response<List<Product>> getProductsByCategoryName(String categoryName);

    /**
     * 创建新商品。
     *
     * @param product 商品实体对象，包含必要的商品信息
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createProduct(Product product);

    /**
     * 更新商品信息。
     *
     * @param product 商品实体对象，必须包含有效的 ID
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateProduct(Product product);

    /**
     * 删除商品（逻辑删除，不会物理移除数据）。
     *
     * @param id 商品的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> deleteProduct(long id);

    /**
     * 获取系统中商品的总数量。
     *
     * @return 包含商品总数的响应对象
     */
    Response<Long> getProductCount();

    /**
     * 检查指定商品 ID 是否存在。
     *
     * @param id 商品的唯一标识
     * @return 存在则返回 {@code true}，否则 {@code false}
     */
    Response<Boolean> productExists(long id);

    /**
     * 检查指定商品名称是否存在。
     *
     * @param name 商品名称
     * @return 存在则返回 {@code true}，否则 {@code false}
     */
    Response<Boolean> productNameExists(String name);

    /**
     * 更新商品库存。
     *
     * @param id       商品的唯一标识
     * @param newStock 更新后的库存数量，必须大于等于零
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateProductStock(long id, int newStock);

    /**
     * 更新商品状态（例如：上架/下架）。
     *
     * @param id     商品的唯一标识
     * @param status 商品状态（如：0=下架，1=上架）
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateProductStatus(long id, int status);
}
